Fantastico modulo comunitario

Object Relational Mapping per fibjs

Stato di costruzione

installare

1
npm install fib-orm

test

1
npm run ci

Supporto DBMS

  • MySQL e MariaDB
  • SQLite

Caratteristiche

fib-orm aggiunge un set di metodi di versione sincrona sull'oggetto node-orm.

introduzione

Questo è un modulo di mappatura relazionale di oggetti fibjs.

Un esempio:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
var orm = require("fib-orm"); var db = orm.connectSync("mysql://username:password@host/database"); var Person = db.define("person", { name : String, surname : String, age : Number, // FLOAT male : Boolean, continent : [ "Europe", "America", "Asia", "Africa", "Australia", "Antartica" ], // ENUM type photo : Buffer, // BLOB/BINARY data : Object // JSON encoded }, { methods: { fullName: function () { return this.name + ' ' + this.surname; } }, validations: { age: orm.enforce.ranges.number(18, undefined, "under-age") } }); // add the table to the database db.syncSync(); // add a row to the person table Person.createSync({ id: 1, name: "John", surname: "Doe", age: 27 }); // query the person table by surname var people = Person.findSync({ surname: "Doe" }); // SQL: "SELECT * FROM person WHERE surname = 'Doe'" console.log("People found: %d", people.length); console.log("First person: %s, age %d", people[0].fullName(), people[0].age); people[0].age = 16; people[0].saveSync();

La versione di node.js come questa:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
var orm = require("orm"); orm.connect("mysql://username:password@host/database", function (err, db) { if (err) throw err; var Person = db.define("person", { name : String, surname : String, age : Number, // FLOAT male : Boolean, continent : [ "Europe", "America", "Asia", "Africa", "Australia", "Antartica" ], // ENUM type photo : Buffer, // BLOB/BINARY data : Object // JSON encoded }, { methods: { fullName: function () { return this.name + ' ' + this.surname; } }, validations: { age: orm.enforce.ranges.number(18, undefined, "under-age") } }); // add the table to the database db.sync(function(err) { if (err) throw err; // add a row to the person table Person.create({ id: 1, name: "John", surname: "Doe", age: 27 }, function(err) { if (err) throw err; // query the person table by surname Person.find({ surname: "Doe" }, function (err, people) { // SQL: "SELECT * FROM person WHERE surname = 'Doe'" if (err) throw err; console.log("People found: %d", people.length); console.log("First person: %s, age %d", people[0].fullName(), people[0].age); people[0].age = 16; people[0].save(function (err) { // err.msg = "under-age"; }); }); }); }); });

Documentazione

Fibjs non ha aggiunto nuove funzioni, lo sviluppo di documenti può fare riferimento a node-orm, è sufficiente modificare la chiamata asincrona in versione sincrona.wiki .

Impostazioni

Vedere le informazioni nel wiki .

Collegamento

Vedere le informazioni nel wiki .

Modelli

Un modello è un'astrazione su una o più tabelle di database.I modelli supportano le associazioni (più sotto).Si presume che il nome del modello corrisponda al nome della tabella.

I modelli supportano i comportamenti per l'accesso e la manipolazione dei dati della tabella.

Definizione di modelli

Vedere le informazioni nel wiki .

Properties

Vedere le informazioni nel wiki .

Instance Methods

Vengono passati durante la definizione del modello.

1 2 3 4 5 6 7 8 9 10 11 12 13
var Person = db.define('person', { name : String, surname : String }, { methods: { fullName: function () { return this.name + ' ' + this.surname; } } }); var person = Person.getSync(4); console.log( person.fullName() );

Model Methods

Sono definiti direttamente sul modello.

1 2 3 4 5 6 7 8 9
var Person = db.define('person', { name : String, height : { type: 'integer' } }); Person.tallerThan = function(height) { return this.findSync({ height: orm.gt(height) }); }; var tallPeople = Person.tallerThan( 192);

Caricamento dei modelli [NON SUPPORTO]

I modelli possono essere in moduli separati.Assicurati semplicemente che il modulo che contiene i modelli utilizzi module.export per pubblicare una funzione che accetti la connessione al database, quindi carica i tuoi modelli come preferisci.

Nota: usando questa tecnica puoi avere carichi a cascata.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
// your main file (after connecting) db.loadSync("./models"); // loaded! var Person = db.models.person; var Pet = db.models.pet; // models.js module.exports = function (db) { db.loadSync("./models-extra"); db.define('person', { name : String }); }; // models-extra.js module.exports = function (db) { db.define('pet', { name : String }); };

Sincronizzazione dei modelli

Vedere le informazioni nel wiki .

Abbandonare i modelli

Vedere le informazioni nel wiki .

Opzioni avanzate

ORM2 ti consente alcune modifiche avanzate alle definizioni del tuo modello, che puoi configurare tramite le impostazioni o nella chiamata a definequando imposti il ​​modello.

Ad esempio, ogni istanza del modello ha un ID univoco nel database. Questa colonna della tabella viene aggiunta automaticamente e chiamata "id" per impostazione predefinita.
Se definisci la tua key: truecolonna, "id" non verrà aggiunto:

1 2 3 4 5 6 7 8 9 10 11 12
var Person = db.define("person", { personId : { type: 'serial', key: true }, name : String }); // You can also change the default "id" property name globally: db.settings.set("properties.primary_key", "UID"); // ..and then define your Models var Pet = db.define("pet", { name : String });

Il modello dell'animale domestico avrà 2 colonne, una UIDe una name.

È anche possibile avere chiavi composte:

1 2 3 4
var Person = db.define("person", { firstname : { type: 'text', key: true }, lastname : { type: 'text', key: true } });

Altre opzioni:

  • identityCache : (predefinito: false) Impostalo trueper abilitare la cache delle identità ( Singletons ) o impostare un valore di timeout (in secondi);
  • autoSave : (predefinito: false) Impostalo per truesalvare un'istanza subito dopo aver modificato qualsiasi proprietà;
  • autoFetch : (predefinito: false) Impostalo trueper recuperare le associazioni durante il recupero di un'istanza dal database;
  • autoFetchLimit: (predefinito: 1) Se autoFetchè abilitato, definisce quanti telai (associazioni di associazioni) si desidera recuperare automaticamente.

Ganci

Vedere le informazioni nel wiki .

Trovando gli oggetti

Model.getSync(id, [ options ])

Per ottenere un elemento specifico dal database utilizzare Model.get.

1 2
var person = Person.getSync(123); // finds person with id = 123

Model.findSync([ conditions ] [, options ] [, limit ] [, order ])

Trovare uno o più elementi ha più opzioni, ognuna può essere data in nessun ordine di parametro specifico.Deve optionsessere solo dopo conditions(anche se è un oggetto vuoto).

1 2
var people = Person.findSync({ name: "John", surname: "Doe" }, 3); // finds people with name='John' AND surname='Doe' and returns the first 3

Se hai bisogno di ordinare i risultati perché stai limitando o solo perché vuoi che siano ordinati, fai:

1 2 3 4 5 6
var people = Person.findSync({ surname: "Doe" }, "name"); // finds people with surname='Doe' and returns sorted by name ascending people = Person.findSync({ surname: "Doe" }, [ "name", "Z" ]); // finds people with surname='Doe' and returns sorted by name descending // ('Z' means DESC; 'A' means ASC - default)

Ci sono più opzioni che puoi passare per trovare qualcosa.Queste opzioni sono passate in un secondo oggetto:

1 2
var people = Person.findSync({ surname: "Doe" }, { offset: 2 }); // finds people with surname='Doe', skips the first 2 and returns the others

Puoi anche utilizzare SQL non elaborato durante la ricerca, come documentato nella sezione Concatenamento di seguito.

Model.countSync([ conditions])

Se vuoi solo contare il numero di elementi che soddisfano una condizione puoi semplicemente usare .count()invece di trovarli tutti e contare.Questo dirà effettivamente al server database di fare un conteggio (non saràfatto nel processo del nodo stesso ).

1 2
var count = Person.countSync({ surname: "Doe" }); console.log("We have %d Does in our db", count);

Model.existsSync([ conditions])

Simile a .count(), questo metodo controlla solo se il conteggio è maggiore di zero o meno.

1 2
var exists = Person.existsSync({ surname: "Doe" }); console.log("We %s Does in our db", exists ? "have" : "don't have");

Aggregating Functions

È possibile passare un Arrayof properties per selezionare solo alcune proprietà e an Objectè accettato anche per definire le condizioni.

Ecco un esempio per illustrare come utilizzare .groupBy():

1 2 3
//The same as "select avg(weight), age from person where country='someCountry' group by age;" var stats = Person.aggregate(["age"], { country: "someCountry" }).avg("weight").groupBy("age").getSync(); // stats is an Array, each item should have 'age' and 'avg_weight'

.aggregate()Metodi di base

  • .limit(): puoi passare un numero come limite o due numeri rispettivamente come offset e limite
  • .order(): uguale aModel.find().order()

.aggregate()Metodi aggiuntivi

  • min
  • max
  • avg
  • sum
  • count(c'è una scorciatoia per questo - Model.count)

Ci sono più funzioni aggregate a seconda del driver (funzioni matematiche per esempio).

Chaining

Se preferisci una sintassi meno complicata, puoi concatenare .find()non fornendo un parametro di callback.

1 2 3
var people = Person.find({ surname: "Doe" }).limit(3).offset(2).only("name", "surname").runSync(); // finds people with surname='Doe', skips first 2 and limits to 3 elements, // returning only 'name' and 'surname' properties

Se vuoi saltare solo una o due proprietà, puoi chiamare .omit()invece di .only.

Il concatenamento consente query più complicate.Ad esempio, possiamo cercare specificando SQL personalizzato:

1
Person.find({ age: 18 }).where("LOWER(surname) LIKE ?", ['dea%']).allSync( ... );

È una cattiva pratica eseguire manualmente l'escape dei parametri SQL poiché è soggetto a errori ed espone l'applicazione all'iniezione SQL.La ?sintassi si occupa dell'escape per te, sostituendo in modo sicuro il punto interrogativo nella query con i parametri forniti.Puoi anche concatenare più whereclausole come necessario.

.find, .where& .allfare la stessa cosa; sono tutti intercambiabili e collegabili.

Puoi anche ordero orderRaw:

1 2 3
Person.find({ age: 18 }).order('-name').allSync( ... ); // see the 'Raw queries' section below for more details Person.find({ age: 18 }).orderRaw("?? DESC", ['age']).allSync( ... );

Puoi anche concatenare e ottenere solo il conteggio alla fine.In questo caso, offset, limite e ordine vengono ignorati.

1 2
var people = Person.find({ surname: "Doe" }).countSync(); // people = number of people with surname="Doe"

È disponibile anche l'opzione per rimuovere gli elementi selezionati.Si noti che una rimozione concatenata non eseguirà alcun hook.

1 2
Person.find({ surname: "Doe" }).removeSync(); // Does gone..

Puoi anche apportare modifiche alle tue istanze utilizzando i comuni metodi di attraversamento dell'array e salvare tutto alla fine.

1 2 3 4 5 6 7 8 9 10 11 12 13
Person.find({ surname: "Doe" }).each(function (person) { person.surname = "Dean"; }).save(function (err) { // done! }); Person.find({ surname: "Doe" }).each().filter(function (person) { return person.age >= 18; }).sort(function (person1, person2) { return person1.age < person2.age; }).get(function (people) { // get all people with at least 18 years, sorted by age });

Ovviamente puoi farlo direttamente su .find(), ma per alcuni compiti più complicati può essere molto utile.

Model.find()non restituisce un Array quindi non puoi semplicemente concatenare direttamente.Per avviare il concatenamento devi chiamare .each()(con un callback opzionale se vuoi attraversare l'elenco).È quindi possibile utilizzare le funzioni comuni .filter()e più di una volta..sort().forEach()

Alla fine (o durante il processo...) puoi chiamare:

  • .countSync()se vuoi solo sapere quanti oggetti ci sono;
  • .getSync()recuperare l'elenco;
  • .saveSync()per salvare tutte le modifiche agli elementi.

Condizioni

Le condizioni sono definite come un oggetto in cui ogni chiave è una proprietà (colonna della tabella). Tutte le chiavi dovrebbero essere concatenate dal logico . ANDI valori sono considerati corrispondere esattamente, a meno che tu non stia passando un Array. In questo caso è considerato un elenco con cui confrontare la proprietà.

1 2
{ col1: 123, col2: "foo" } // `col1` = 123 AND `col2` = 'foo' { col1: [ 1, 3, 5 ] } // `col1` IN (1, 3, 5)

Se hai bisogno di altri confronti, devi usare un oggetto speciale creato da alcune funzioni di supporto, ecco alcuni esempi per descriverlo:

1 2 3 4 5 6 7 8 9 10 11
{ col1: orm.eq(123) } // `col1` = 123 (default) { col1: orm.ne(123) } // `col1` <> 123 { col1: orm.gt(123) } // `col1` > 123 { col1: orm.gte(123) } // `col1` >= 123 { col1: orm.lt(123) } // `col1` < 123 { col1: orm.lte(123) } // `col1` <= 123 { col1: orm.between(123, 456) } // `col1` BETWEEN 123 AND 456 { col1: orm.not_between(123, 456) } // `col1` NOT BETWEEN 123 AND 456 { col1: orm.like(12 + "%") } // `col1` LIKE '12%' { col1: orm.not_like(12 + "%") } // `col1` NOT LIKE '12%' { col1: orm.not_in([1, 4, 8]) } // `col1` NOT IN (1, 4, 8)

Query grezze

1 2 3 4 5 6 7 8 9 10 11 12 13
var data = db.driver.execQuerySync("SELECT id, email FROM user") // You can escape identifiers and values. // For identifier substitution use: ?? // For value substitution use: ? var data = db.driver.execQuerySync( "SELECT user.??, user.?? FROM user WHERE user.?? LIKE ? AND user.?? > ?", ['id', 'name', 'name', 'john', 'id', 55]) // Identifiers don't need to be scaped most of the time var data = db.driver.execQuerySync( "SELECT user.id, user.name FROM user WHERE user.name LIKE ? AND user.id > ?", ['john', 55])

Identity pattern

È possibile utilizzare il modello di identità (disattivato per impostazione predefinita). Se abilitato, più query diverse daranno lo stesso risultato: otterrai lo stesso oggetto. Se disponi di altri sistemi che possono modificare il tuo database o devi chiamare alcuni manuali query SQL, non dovresti usare questa funzione. È anche noto per causare alcuni problemi con complesse relazioni di recupero automatico. Usalo a tuo rischio.

Può essere abilitato/disabilitato per modello:

1 2 3 4 5
var Person = db.define('person', { name : String }, { identityCache : true });

e anche a livello globale:

1 2
var db = orm.connectSync('...'); db.settings.set('instance.identityCache', true);

La cache delle identità può essere configurata per scadere dopo un periodo di tempo passando un numero invece di un valore booleano.Il numero sarà considerato il timeout della cache in secondi (è possibile utilizzare la virgola mobile).

Nota : un'eccezione relativa alla memorizzazione nella cache è che non verrà utilizzata se un'istanza non viene salvata.Ad esempio, se recuperi una persona e poi la modifichi, mentre non viene salvata non verrà passata dalla cache.

Creazione di articoli

Model.createSync(items)

Per inserire nuovi elementi nel database utilizzare Model.create.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
var items = Person.createSync([ { name: "John", surname: "Doe", age: 25, male: true }, { name: "Liza", surname: "Kollan", age: 19, male: false } ]); // items - array of inserted items

Aggiornamento degli elementi

Ogni elemento restituito ha le proprietà che sono state definite nel modello e anche un paio di metodi che puoi utilizzare per modificare ciascun elemento.

1 2 3 4 5
var John = Person.getSync(1); John.name = "Joe"; John.surname = "Doe"; John.saveSync(); console.log("saved!");

L'aggiornamento e quindi il salvataggio di un'istanza possono essere eseguiti in una singola chiamata:

1 2 3
var John = Person.getSync(1); John.saveSync({ name: "Joe", surname: "Doe" }); console.log("saved!");

Se vuoi rimuovere un'istanza, fai semplicemente:

1 2 3 4
// you could do this without even fetching it, look at Chaining section above var John = Person.getSync(1); John.removeSync(); console.log("removed!");

Convalide

Vedere le informazioni nel wiki .

Associazioni

Un'associazione è una relazione tra una o più tabelle.

hasOne

È una relazione molti a uno . È uguale a appartiene a.
Ad esempio: Animal.hasOne('owner', Person).
Animal può avere un solo proprietario, ma Person può avere molti animali.
Animal avrà la owner_idproprietà aggiunta automaticamente.

Saranno disponibili le seguenti funzioni:

1 2 3 4
animal.getOwnerSync() // Gets owner animal.setOwnerSync(person) // Sets owner_id animal.hasOwnerSync() // Checks if owner exists animal.removeOwnerSync() // Sets owner_id to 0

Trova catena

Anche l'associazione hasOne è compatibile con chain find Usando l'esempio sopra, possiamo farlo per accedere a una nuova istanza di un oggetto ChainFind:

1
Animal.findByOwner({ /* options */ })

Accesso inverso

1
Animal.hasOne('owner', Person, {reverse: 'pets'})

aggiungerà quanto segue:

1 2 3 4 5 6
// Instance methods person.getPetsSync(function..) person.setPetsSync(cat, function..) // Model methods Person.findByPets({ /* options */ }) // returns ChainFind object

hasMany

È una relazione molti a molti (include la tabella di unione).Es
.: Patient.hasMany('doctors', Doctor, { why: String }, { reverse: 'patients', key: true }).Il
paziente può avere molti medici diversi.Ogni medico può avere molti pazienti diversi.

Questo creerà una tabella di join patient_doctorsquando chiami Patient.sync():

nome della colonna tipo
ID_paziente Intero (chiave composita)
doctor_id Intero (chiave composita)
Perché variabile(255)

Saranno disponibili le seguenti funzioni:

1 2 3 4 5 6 7 8 9 10 11 12
patient.getDoctorsSync() // List of doctors patient.addDoctorsSync(docs) // Adds entries to join table patient.setDoctorsSync(docs) // Removes existing entries in join table, adds new ones patient.hasDoctorsSync(docs) // Checks if patient is associated to specified doctors patient.removeDoctorsSync(docs) // Removes specified doctors from join table doctor.getPatientsSync() etc... // You can also do: patient.doctors = [doc1, doc2]; patient.saveSync()

Per associare un medico a un paziente:

1
patient.addDoctorSync(surgeon, {why: "remove appendix"})

che verrà aggiunto {patient_id: 4, doctor_id: 6, why: "remove appendix"}alla tabella di join.

getAccessor

Questa funzione di accesso in questo tipo di associazione restituisce a ChainFindse non passa una richiamata.Ciò significa che puoi fare cose come:

1 2
var doctors = patient.getDoctors().order("name").offset(1).runSync()); // ... all doctors, ordered by name, excluding first one

extendsTo

Se vuoi dividere forse le proprietà facoltative in diverse tabelle o raccolte.Ogni estensione sarà in una nuova tabella, dove l'identificatore univoco di ogni riga è l'ID dell'istanza del modello principale.Ad esempio:

1 2 3 4 5 6 7
var Person = db.define("person", { name : String }); var PersonAddress = Person.extendsTo("address", { street : String, number : Number });

Questo creerà una tabella personcon colonne ide name. L'estensione creerà una tabella person_addresscon colonne person_id, streete number. I metodi disponibili nel Personmodello sono simili a hasOne un'associazione. In questo esempio potresti chiamare .getAddress(cb), .setAddress(Address, cb), ..

Nota: non devi salvare il risultato da Person.extendsTo.Restituisce un modello esteso.Puoi usarlo per interrogare direttamente questa tabella estesa (e anche trovare il modello correlato) ma dipende da te.Se vuoi solo accedervi Usando il modello originale puoi semplicemente scartare il reso.

Examples & options

Se hai una relazione da 1 a n, dovresti usare hasOnel'associazione (appartiene a).

1 2 3 4 5 6 7 8 9 10 11 12 13
var Person = db.define('person', { name : String }); var Animal = db.define('animal', { name : String }); Animal.hasOne("owner", Person); // creates column 'owner_id' in 'animal' table // get animal with id = 123 var animal = Animal.getSync(123); // animal is the animal model instance, if found var person = animal.getOwnerSync(); // if animal has really an owner, person points to it

È possibile contrassegnare il owner_idcampo come richiesto nel database specificando l' requiredopzione:

1
Animal.hasOne("owner", Person, { required: true });

Se un campo non è obbligatorio, ma deve essere validato anche se non è presente, specificare l' alwaysValidateopzione (questo può accadere, ad esempio quando la validazione di un campo nullo dipende da altri campi del record)

1
Animal.hasOne("owner", Person, { required: false, alwaysValidate: true });

Se preferisci utilizzare un altro nome per il campo (owner_id) puoi modificare questo parametro nelle impostazioni.

1
db.settings.set("properties.association_key", "{field}_{name}"); // {name} will be replaced by 'owner' and {field} will be replaced by 'id' in this case

Nota: questa operazione deve essere eseguita prima che venga specificata l'associazione.

Le hasManyassociazioni possono avere proprietà aggiuntive nella tabella delle associazioni.

1 2 3 4 5 6 7 8 9 10 11
var Person = db.define('person', { name : String }); Person.hasMany("friends", { rate : Number }, {}, { key: true }); var John = Person.getSync(123); var friends = John.getFriendsSync(); // assumes rate is another column on table person_friends // you can access it by going to friends[N].extra.rate

Se preferisci, puoi attivare autoFetch.In questo modo le associazioni vengono recuperate automaticamente quando ottieni o trovi istanze di un modello.

1 2 3 4 5 6 7 8 9 10 11 12
var Person = db.define('person', { name : String }); Person.hasMany("friends", { rate : Number }, { key : true, // Turns the foreign keys in the join table into a composite key autoFetch : true }); var John = Person.getSync(123); // no need to do John.getFriends() , John already has John.friends Array

È inoltre possibile definire questa opzione a livello globale anziché in base all'associazione.

1 2 3 4 5 6 7 8 9 10
var Person = db.define('person', { name : String }, { autoFetch : true }); Person.hasMany("friends", { rate : Number }, { key: true });

Le associazioni possono effettuare chiamate al modello associato utilizzando l' reverseopzione. Ad esempio, se si dispone di un'associazione da ModelA a ModelB, è possibile creare una funzione di accesso in ModelB per ottenere istanze da ModelA. Confusione? Guarda l'esempio successivo.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
var Pet = db.define('pet', { name : String }); var Person = db.define('person', { name : String }); Pet.hasOne("owner", Person, { reverse : "pets" }); var pets = Person(4).getPetsSync(); // although the association was made on Pet, // Person will have an accessor (getPets) // // In this example, ORM will fetch all pets // whose owner_id = 4

Ciò ha ancora più senso quando si hanno hasManyassociazioni poiché è possibile gestire le associazioni da molti a molti da entrambe le parti.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
var Pet = db.define('pet', { name : String }); var Person = db.define('person', { name : String }); Person.hasMany("pets", Pet, { bought : Date }, { key : true, reverse : "owners" }); Person(1).getPetsSync(...); Pet(2).getOwnersSync(...);

Supporto per le transazioni

È possibile utilizzare la funzione di transazione di basso livello per elaborare la transazione db.

1 2 3 4 5 6
db.begin(); ... if(err) db.rollback(); else db.commit();

Oppure puoi usare trans per semplificare l'elaborazione.

1 2 3 4
var result = db.trans(() => { ... return result; });

Aggiunta di adattatori di database esterni

Per aggiungere un adattatore di database esterno a orm, chiama il addAdaptermetodo, passando l'alias da utilizzare per la connessione con questo adattatore, insieme al costruttore per l'adattatore:

1
require('orm').addAdapter('cassandra', CassandraAdapter);

Vederethe documentation for creating adaptersper ulteriori dettagli.