SQLite
أضيف في: v22.5.0
[مستقر: 1 - تجريبي]
مستقر: 1 استقرار: 1.1 - تطوير نشط.
رمز المصدر: lib/sqlite.js
تسهل وحدة node:sqlite
العمل مع قواعد بيانات SQLite. للوصول إليها:
import sqlite from 'node:sqlite'
const sqlite = require('node:sqlite')
هذه الوحدة متاحة فقط ضمن مخطط node:
.
يُظهر المثال التالي الاستخدام الأساسي لوحدة node:sqlite
لفتح قاعدة بيانات في الذاكرة، وكتابة البيانات في قاعدة البيانات، ثم قراءة البيانات مرة أخرى.
import { DatabaseSync } from 'node:sqlite'
const database = new DatabaseSync(':memory:')
// تنفيذ عبارات SQL من سلاسل.
database.exec(`
CREATE TABLE data(
key INTEGER PRIMARY KEY,
value TEXT
) STRICT
`)
// إنشاء بيان مُعد لإدراج البيانات في قاعدة البيانات.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// تنفيذ البيان المُعد بقيم مُرتبطة.
insert.run(1, 'hello')
insert.run(2, 'world')
// إنشاء بيان مُعد لقراءة البيانات من قاعدة البيانات.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// تنفيذ البيان المُعد وتسجيل مجموعة النتائج.
console.log(query.all())
// يطبع: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]
'use strict'
const { DatabaseSync } = require('node:sqlite')
const database = new DatabaseSync(':memory:')
// تنفيذ عبارات SQL من سلاسل.
database.exec(`
CREATE TABLE data(
key INTEGER PRIMARY KEY,
value TEXT
) STRICT
`)
// إنشاء بيان مُعد لإدراج البيانات في قاعدة البيانات.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// تنفيذ البيان المُعد بقيم مُرتبطة.
insert.run(1, 'hello')
insert.run(2, 'world')
// إنشاء بيان مُعد لقراءة البيانات من قاعدة البيانات.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// تنفيذ البيان المُعد وتسجيل مجموعة النتائج.
console.log(query.all())
// يطبع: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]
الصنف: DatabaseSync
مضاف في: v22.5.0
يمثل هذا الصنف اتصالاً واحداً بالتوصيل بقاعدة بيانات SQLite. يتم تنفيذ جميع واجهات برمجة التطبيقات المعروضة بواسطة هذا الصنف بشكل متزامن.
new DatabaseSync(location[, options])
مضاف في: v22.5.0
location
<سلسلة> موقع قاعدة البيانات. يمكن تخزين قاعدة بيانات SQLite في ملف أو بالكامل في الذاكرة. لاستخدام قاعدة بيانات مدعومة بملف، يجب أن يكون الموقع مسار ملف. لاستخدام قاعدة بيانات في الذاكرة، يجب أن يكون الموقع الاسم الخاص':memory:'
.options
<كائن> خيارات التكوين لاتصال قاعدة البيانات. يتم دعم الخيارات التالية:open
<قيمة منطقية> إذا كانتtrue
، فسيتم فتح قاعدة البيانات بواسطة المُنشئ. عندما تكون هذه القيمةfalse
، يجب فتح قاعدة البيانات عبر طريقةopen()
. افتراضيًا:true
.readOnly
<قيمة منطقية> إذا كانتtrue
، فسيتم فتح قاعدة البيانات في وضع القراءة فقط. إذا لم تكن قاعدة البيانات موجودة، فستفشل عملية فتحها. افتراضيًا:false
.enableForeignKeyConstraints
<قيمة منطقية> إذا كانتtrue
، فسيتم تمكين قيود المفاتيح الأجنبية. يُوصى بذلك، ولكن يمكن تعطيله للتوافق مع مخططات قواعد البيانات القديمة. يمكن تمكين وإنزال تطبيق قيود المفاتيح الأجنبية بعد فتح قاعدة البيانات باستخدامPRAGMA foreign_keys
. افتراضيًا:true
.enableDoubleQuotedStringLiterals
<قيمة منطقية> إذا كانتtrue
، فسيقبل SQLite الوسائط النصية المحاطة بعلامات اقتباس مزدوجة. لا يُوصى بذلك، ولكن يمكن تمكينه للتوافق مع مخططات قواعد البيانات القديمة. افتراضيًا:false
.allowExtension
<قيمة منطقية> إذا كانتtrue
، فسيتم تمكين دالة SQLloadExtension
وطريقةloadExtension()
. يمكنك الاتصال بـenableLoadExtension(false)
لاحقًا لتعطيل هذه الميزة. افتراضيًا:false
.
يقوم بإنشاء مثيل جديد من DatabaseSync
.
database.close()
مضاف في: v22.5.0
يقوم بإغلاق اتصال قاعدة البيانات. يتم رمي استثناء إذا لم تكن قاعدة البيانات مفتوحة. هذه الطريقة عبارة عن غلاف حول sqlite3_close_v2()
.
database.loadExtension(path)
مضاف في: v23.5.0
path
<string> المسار إلى مكتبة المشاركة التي سيتم تحميلها.
يقوم بتحميل مكتبة مشاركة في اتصال قاعدة البيانات. هذه الطريقة عبارة عن غلاف حول sqlite3_load_extension()
. من الضروري تمكين خيار allowExtension
عند إنشاء مثيل DatabaseSync
.
database.enableLoadExtension(allow)
مضاف في: v23.5.0
allow
<boolean> ما إذا كان يُسمح بتحميل الإضافات.
يقوم بتمكين أو تعطيل دالة SQL loadExtension
، وطريقة loadExtension()
. عندما يكون allowExtension
false
عند الإنشاء، لا يمكنك تمكين تحميل الإضافات لأسباب أمنية.
database.exec(sql)
مضاف في: v22.5.0
sql
<string> سلسلة SQL ليتم تنفيذها.
تتيح هذه الطريقة تنفيذ جملة أو أكثر من جمل SQL دون إرجاع أي نتائج. هذه الطريقة مفيدة عند تنفيذ جمل SQL التي تم قراءتها من ملف. هذه الطريقة عبارة عن غلاف حول sqlite3_exec()
.
database.function(name[, options], function)
مضاف في: v23.5.0
name
<string> اسم دالة SQLite التي سيتم إنشاؤها.options
<Object> إعدادات تكوين اختيارية للدالة. يتم دعم الخصائص التالية:deterministic
<boolean> إذا كانتtrue
، فسيتم تعيين علمSQLITE_DETERMINISTIC
على الدالة التي تم إنشاؤها. الافتراضي:false
.directOnly
<boolean> إذا كانتtrue
، فسيتم تعيين علمSQLITE_DIRECTONLY
على الدالة التي تم إنشاؤها. الافتراضي:false
.useBigIntArguments
<boolean> إذا كانتtrue
، فسيتم تحويل الوسائط الصحيحة إلىBigInt
s. إذا كانتfalse
، فسيتم تمرير الوسائط الصحيحة كأرقام JavaScript. الافتراضي:false
.varargs
<boolean> إذا كانتtrue
، فيمكن لـfunction
قبول عدد متغير من الوسائط. إذا كانتfalse
، يجب استدعاءfunction
باستخدامfunction.length
من الوسائط بالضبط. الافتراضي:false
.
function
<Function> دالة JavaScript التي سيتم استدعاؤها عند استدعاء دالة SQLite.
تُستخدم هذه الطريقة لإنشاء دوال مُعرفة بواسطة المستخدم في SQLite. هذه الطريقة عبارة عن غلاف حول sqlite3_create_function_v2()
.
database.open()
مُضاف في: v22.5.0
يفتح قاعدة البيانات المحددة في وسيطة location
لباني DatabaseSync
. يجب استخدام هذه الطريقة فقط عندما لا يتم فتح قاعدة البيانات عبر الباني. يتم طرح استثناء إذا كانت قاعدة البيانات مفتوحة بالفعل.
database.prepare(sql)
مُضاف في: v22.5.0
sql
<string> سلسلة SQL لترجمة إلى بيان مُعد.- مُخرجات: <StatementSync> البيان المُعد.
يُجمّع بيان SQL في بيان مُعد. هذه الطريقة عبارة عن غلاف حول sqlite3_prepare_v2()
.
database.createSession([options])
مُضاف في: v23.3.0
options
<Object> خيارات التكوين للجلسة.table
<string> جدول محدد لتتبع التغييرات له. بشكل افتراضي، يتم تتبع التغييرات على جميع الجداول.db
<string> اسم قاعدة البيانات التي سيتم تتبعها. هذا مفيد عندما يتم إضافة قواعد بيانات متعددة باستخدامATTACH DATABASE
. الافتراضي:'main'
.
مُخرجات: <Session> مؤشر جلسة.
يُنشئ ويُرفق جلسة بقاعدة البيانات. هذه الطريقة عبارة عن غلاف حول sqlite3session_create()
و sqlite3session_attach()
.
database.applyChangeset(changeset[, options])
مُضاف في: v23.3.0
changeset
<Uint8Array> مجموعة تغييرات ثنائية أو مجموعة تصحيحات.options
<Object> خيارات التكوين لكيفية تطبيق التغييرات.filter
<Function> تخطي التغييرات التي، عند تقديم اسم الجدول المُستهدف إلى هذه الدالة، تُرجع قيمة صحيحة. بشكل افتراضي، يتم محاولة تطبيق جميع التغييرات.onConflict
<number> يُحدد كيفية التعامل مع التعارضات. الافتراضي:SQLITE_CHANGESET_ABORT
.SQLITE_CHANGESET_OMIT
: يتم حذف التغييرات المتعارضة.SQLITE_CHANGESET_REPLACE
: تحل التغييرات المتعارضة محل القيم الموجودة.SQLITE_CHANGESET_ABORT
: الإلغاء عند حدوث تعارض والتراجع عن قاعدة البيانات.
مُخرجات: <boolean> ما إذا تم تطبيق مجموعة التغييرات بنجاح دون إلغاء.
يتم طرح استثناء إذا لم تكن قاعدة البيانات مفتوحة. هذه الطريقة عبارة عن غلاف حول sqlite3changeset_apply()
.
const sourceDb = new DatabaseSync(':memory:')
const targetDb = new DatabaseSync(':memory:')
sourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)')
targetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)')
const session = sourceDb.createSession()
const insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
insert.run(1, 'hello')
insert.run(2, 'world')
const changeset = session.changeset()
targetDb.applyChangeset(changeset)
// الآن بعد تطبيق مجموعة التغييرات، تحتوي targetDb على نفس البيانات الموجودة في sourceDb.
الصنف: Session
مضاف في: v23.3.0
session.changeset()
مضاف في: v23.3.0
- القيمة المُرجعة: <Uint8Array> مجموعة تغييرات ثنائية يمكن تطبيقها على قواعد بيانات أخرى.
يسترد مجموعة تغييرات تحتوي على جميع التغييرات منذ إنشاء مجموعة التغييرات. يمكن استدعاء هذه الدالة عدة مرات. يتم إطلاق استثناء إذا لم تكن قاعدة البيانات أو الجلسة مفتوحة. هذه الدالة عبارة عن غلاف حول sqlite3session_changeset()
.
session.patchset()
مضاف في: v23.3.0
- القيمة المُرجعة: <Uint8Array> مجموعة تصحيح ثنائية يمكن تطبيقها على قواعد بيانات أخرى.
على غرار الطريقة المذكورة أعلاه، لكنها تولد مجموعة تصحيح أكثر إيجازًا. انظر مجاميع التغييرات ومجاميع التصحيح في وثائق SQLite. يتم إطلاق استثناء إذا لم تكن قاعدة البيانات أو الجلسة مفتوحة. هذه الدالة عبارة عن غلاف حول sqlite3session_patchset()
.
session.close()
.
يغلق الجلسة. يتم إطلاق استثناء إذا لم تكن قاعدة البيانات أو الجلسة مفتوحة. هذه الدالة عبارة عن غلاف حول sqlite3session_delete()
.
الصنف: StatementSync
مضاف في: v22.5.0
يمثل هذا الصنف بيانًا مُعدًا واحدًا prepared statement. لا يمكن إنشاء مثيل لهذا الصنف عبر مُنشئه. بدلاً من ذلك، يتم إنشاء المثيلات عبر طريقة database.prepare()
. جميع واجهات برمجة التطبيقات التي يعرضها هذا الصنف تُنفذ بشكل متزامن.
البيان المُعد هو تمثيل ثنائي فعال للـ SQL المستخدم لإنشائه. يمكن معاملنة البيانات المُعدة، ويمكن استدعاءها عدة مرات بقيم مُرتبطة مختلفة. توفر المعلمات أيضًا حماية ضد هجمات حقن SQL. لهذه الأسباب، تُفضل البيانات المُعدة على سلاسل SQL المصممة يدويًا عند التعامل مع مدخلات المستخدم.
statement.all([namedParameters][, ...anonymousParameters])
مضاف في: v22.5.0
namedParameters
<Object> كائن اختياري يُستخدم لربط المعلمات المسمّاة. تُستخدم مفاتيح هذا الكائن لتكوين التعيين....anonymousParameters
<null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> قيمة أو أكثر لربطها بالمعلمات غير المسمّاة.- القيمة المُرجعة: <Array> مصفوفة من الكائنات. يتوافق كل كائن مع صف تم إرجاعه عن طريق تنفيذ البيان المُعد. تتوافق مفاتيح وقيم كل كائن مع أسماء الأعمدة وقيم الصف.
تنفذ هذه الطريقة بيانًا مُعدًا، وتُعيد جميع النتائج كمصفوفة من الكائنات. إذا لم يُرجع البيان المُعد أي نتائج، تُعيد هذه الطريقة مصفوفة فارغة. يتم ربط معلمات البيان المُعد باستخدام القيم الموجودة في namedParameters
و anonymousParameters
.
statement.expandedSQL
مضاف في: v22.5.0
- <string> نص SQL المصدر الموسّع ليشمل قيم المعلمات.
نص SQL المصدر للبيان المُعد مع مُحلّلات مكان المعلمات المُستبدلة بالقيم التي تم استخدامها أثناء آخر تنفيذ لهذا البيان المُعد. هذه الخاصية هي غلاف حول sqlite3_expanded_sql()
.
statement.get([namedParameters][, ...anonymousParameters])
مضاف في: v22.5.0
namedParameters
<Object> كائن اختياري يُستخدم لربط المعلمات المسماة. تُستخدم مفاتيح هذا الكائن لتكوين التعيين....anonymousParameters
<null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> قيمة أو أكثر لربطها بالمعلمات مجهولة الاسم.- القيمة المُرجعه: <Object> | <undefined> كائن يتوافق مع الصف الأول المُرجع بتنفيذ البيان المُعد. تتوافق مفاتيح وقيم الكائن مع أسماء الأعمدة وقيم الصف. إذا لم يتم إرجاع أي صفوف من قاعدة البيانات، فإن هذه الطريقة تُرجع
undefined
.
تنفذ هذه الطريقة بيانًا مُعدًا، وتُرجع النتيجة الأولى كائنًا. إذا لم يُرجع البيان المُعد أي نتائج، فإن هذه الطريقة تُرجع undefined
. يتم ربط معلمات البيان المُعد باستخدام القيم الموجودة في namedParameters
و anonymousParameters
.
statement.iterate([namedParameters][, ...anonymousParameters])
مضاف في: v23.4.0
namedParameters
<Object> كائن اختياري يُستخدم لربط المعلمات المسماة. تُستخدم مفاتيح هذا الكائن لتكوين التعيين....anonymousParameters
<null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> قيمة أو أكثر لربطها بالمعلمات مجهولة الاسم.- القيمة المُرجعه: <Iterator> مُكرر قابلة للتكرار من الكائنات. يتوافق كل كائن مع صف مُرجع بتنفيذ البيان المُعد. تتوافق مفاتيح وقيم كل كائن مع أسماء الأعمدة وقيم الصف.
تنفذ هذه الطريقة بيانًا مُعدًا، وتُرجع مُكررًا من الكائنات. إذا لم يُرجع البيان المُعد أي نتائج، فإن هذه الطريقة تُرجع مُكررًا فارغًا. يتم ربط معلمات البيان المُعد باستخدام القيم الموجودة في namedParameters
و anonymousParameters
.
statement.run([namedParameters][, ...anonymousParameters])
أضيف في: v22.5.0
namedParameters
<Object> كائن اختياري يُستخدم لربط المعلمات المسماة. تُستخدم مفاتيح هذا الكائن لتكوين التعيين....anonymousParameters
<null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> قيمة أو أكثر لربطها بالمعلمات مجهولة المصدر.- القيمة المُرجعة: <Object>
changes
: <number> | <bigint> عدد الصفوف المُعدلة أو المُدرجة أو المُحذفة بواسطة بيانINSERT
أوUPDATE
أوDELETE
الذي تم إنجازه مؤخراً. هذه الحقل إما رقم أوBigInt
اعتماداً على تكوين البيان المُحضّر. هذه الخاصية هي نتيجة لـsqlite3_changes64()
.lastInsertRowid
: <number> | <bigint> معرف الصف المُدرج مؤخراً. هذه الحقل إما رقم أوBigInt
اعتماداً على تكوين البيان المُحضّر. هذه الخاصية هي نتيجة لـsqlite3_last_insert_rowid()
.
هذه الطريقة تُنفذ بياناً مُحضراً و تُعيد كائناً يُلخص التغييرات الناتجة. يتم ربط معلمات البيان المُحضّر باستخدام القيم الموجودة في namedParameters
و anonymousParameters
.
statement.setAllowBareNamedParameters(enabled)
مضاف في: v22.5.0
enabled
<boolean> يُمَكِّن أو يُعَطِّل دعم ربط المعلمات المسماة بدون حرف البادئة.
تبدأ أسماء معلمات SQLite بحرف بادئة. بشكل افتراضي، يتطلب node:sqlite
وجود حرف البادئة هذا عند ربط المعلمات. ومع ذلك، باستثناء حرف الدولار، تتطلب أحرف البادئة هذه أيضًا اقتباسًا إضافيًا عند استخدامها في مفاتيح الكائنات.
لتحسين سهولة الاستخدام، يمكن استخدام هذه الطريقة للسماح أيضًا بالمعلمات المسماة العارية، والتي لا تتطلب حرف البادئة في رمز JavaScript. هناك بعض التحذيرات التي يجب الانتباه إليها عند تمكين المعلمات المسماة العارية:
- لا يزال حرف البادئة مطلوبًا في SQL.
- لا يزال حرف البادئة مسموحًا به في JavaScript. في الواقع، ستتمتع الأسماء ذات البادئة بأداء ربط أفضل قليلاً.
- سيؤدي استخدام معلمات مسماة غامضة، مثل
$k
و@k
، في نفس بيان التحضير إلى استثناء لأنه لا يمكن تحديد كيفية ربط اسم عارٍ.
statement.setReadBigInts(enabled)
مضاف في: v22.5.0
enabled
<boolean> يُمكّن أو يُعطل استخدامBigInt
عند قراءة حقولINTEGER
من قاعدة البيانات.
عند القراءة من قاعدة البيانات، يتم تعيين قيم SQLite INTEGER
إلى أرقام JavaScript بشكل افتراضي. ومع ذلك، يمكن أن تخزن قيم SQLite INTEGER
قيمًا أكبر من القيم التي يمكن أن تمثلها أرقام JavaScript. في مثل هذه الحالات، يمكن استخدام هذه الطريقة لقراءة بيانات INTEGER
باستخدام JavaScript BigInt
. هذه الطريقة ليس لها أي تأثير على عمليات كتابة قاعدة البيانات حيث يتم دعم الأرقام و BigInt
في جميع الأوقات.
statement.sourceSQL
مضاف في: v22.5.0
- <string> نص SQL المصدر المستخدم لإنشاء بيان التحضير هذا.
نص SQL المصدر لبيان التحضير. هذه الخاصية عبارة عن غلاف حول sqlite3_sql()
.
تحويل النوع بين جافا سكريبت و SQLite
عند كتابة Node.js إلى SQLite أو قراءته منه، من الضروري التحويل بين أنواع بيانات جافا سكريبت وأنواع بيانات SQLite أنواع البيانات. نظرًا لأن جافا سكريبت تدعم المزيد من أنواع البيانات من SQLite، فلا يتم دعم سوى مجموعة فرعية من أنواع بيانات جافا سكريبت. سيؤدي محاولة كتابة نوع بيانات غير مدعوم إلى SQLite إلى استثناء.
SQLite | JavaScript |
---|---|
NULL | <null> |
INTEGER | <number> أو <bigint> |
REAL | <number> |
TEXT | <string> |
BLOB | <Uint8Array> |
sqlite.constants
مضاف في: v23.5.0
كائن يحتوي على ثوابت شائعة الاستخدام لعمليات SQLite.
ثوابت SQLite
يتم تصدير الثوابت التالية بواسطة كائن sqlite.constants
.
ثوابت حل التعارضات
تهدف الثوابت التالية للاستخدام مع database.applyChangeset()
.
الثابت | الوصف |
---|---|
SQLITE_CHANGESET_OMIT | يتم حذف التغييرات المتعارضة. |
SQLITE_CHANGESET_REPLACE | تحل التغييرات المتعارضة محل القيم الموجودة. |
SQLITE_CHANGESET_ABORT | الإلغاء عند مواجهة تغيير تعارضًا وإرجاع قاعدة البيانات. |