بیک اپ، ایکسپورٹ اور امپورٹ

ہر وہ چیز جو Control Center نقل، حوالے یا اپنا سکتا ہے، اور ہر آرٹی فیکٹ کی عین ساخت۔ اصل میں بیک اپ لینے کے لیے بیک اپ اور بحالی دیکھیں؛ اور یہ کہ پائیداری اِس طرح کیوں بٹی ہوئی ہے، جاننے کے لیے ورک اسپیسز اور تنہائی دیکھیں۔

آرٹی فیکٹس

ڈیٹا بیس کی نقل کے تین آرٹی فیکٹس ہیں، جن کے دائرے اور حذف کی پالیسیاں مختلف ہیں۔

آرٹی فیکٹ	کس نے لکھا	شکل	احاطہ
انسٹال اسنیپ شاٹ	server.backupNow	ایک ٹائم اسٹیمپ والی ڈائریکٹری	انسٹال کی ہر ڈیٹا بیس
ورک اسپیس بیک اپ	Workspace backup پائپ لائن	ٹائم اسٹیمپ والی ڈائریکٹری، ایک .db کے ساتھ	ایک ورک اسپیس کی ڈیٹا بیس
ورک اسپیس ایکسپورٹ	workspace.export	ایک واحد .db فائل	ایک ورک اسپیس کی ڈیٹا بیس

یہ سب SQLite کے VACUUM INTO سے لکھے جاتے ہیں، جو زندہ WAL ڈیٹا بیس کے خلاف بھی محفوظ ہے: یہ ایک ریڈ ٹرانزیکشن لیتا ہے، ایک ڈی فرگمنٹ شدہ اور ٹرانزیکشن کے لحاظ سے ہم آہنگ نقل بناتا ہے، اور کبھی سرور روکنے کا تقاضا نہیں کرتا۔

اسنیپ شاٹ کی ساخت

<dataDir>/backups/2026-07-28T09-12-33-000Z/
  manifest.json
  global.db
  <workspaceId>/workspace.db      one directory per workspace

ساخت زندہ ڈیٹا ڈائریکٹری کی عین نقل ہے، اور یہی چیز انسٹال کی بحالی کو ترجمے کے بجائے ایک واپسی نقل بناتی ہے۔ ڈائریکٹری کا نام UTC ٹائم اسٹیمپ ہے جس میں : اور . کو - سے بدل دیا گیا ہوتا ہے، چنانچہ یہ Windows پر فائل سسٹم کے لیے محفوظ ہے اور سادہ متن کی صورت میں زمانی ترتیب سے ترتیب پاتا ہے۔

شیڈول شدہ ورک اسپیس بیک اپس الگ سے <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db پر رہتے ہیں۔ اِن میں کوئی مینی فیسٹ یا global.db شامل نہیں ہوتا اور یہ انسٹال اسنیپ شاٹس نہیں ہیں۔ ہفتہ وار پائپ لائن کا برقراری کا قدم صرف اپنی ورک اسپیس کے اُن بیک اپس کو ہٹاتا ہے جو اُس کی مقرر کردہ عمر (بطور ڈیفالٹ 30 دن) سے پرانے ہوں؛ دستی طور پر بنائے گئے انسٹال اسنیپ شاٹس اُس قدم کے ذریعے کبھی نہیں ہٹائے جاتے۔ server.listBackups صرف انسٹال اسنیپ شاٹس کی فہرست دیتا ہے، نامکمل سمیت۔

manifest.json

فیلڈ	قسم	مطلب
version	int	مینی فیسٹ فارمیٹ کا ورژن۔ اس وقت 1
created_at	ISO-8601 UTC	اسنیپ شاٹ کب لیا گیا
global.file	string	ہمیشہ global.db
global.schema_version	int	گرفت کے وقت GlobalDatabase اسکیما کا ورژن
global.bytes	int	لکھی گئی global.db کا سائز
workspace_schema_version	int	WorkspaceDatabase اسکیما کا ورژن، جو ہر ورک اسپیس فائل میں مشترک ہے
workspaces[]	array	ہر گرفت شدہ ورک اسپیس کے لیے ایک اندراج
workspaces[].workspace_id	string	وہ ورک اسپیس جس کی یہ فائل ہے
workspaces[].file	string	اسنیپ شاٹ روٹ کے حوالے سے پاتھ، <workspaceId>/workspace.db
workspaces[].bytes	int	اُس فائل کا سائز
skipped_workspaces[]	array of string	وہ ورک اسپیسز جنہیں بیک اپ گرفت نہ سکا

کوئی ورک اسپیس اُس وقت چھوڑ دی جاتی ہے جب وہ رجسٹر ہو مگر اُس میں کبھی لکھا نہ گیا ہو (چنانچہ ابھی کوئی فائل موجود نہیں)، یا جب اُس کا VACUUM INTO ناکام ہو جائے۔ دونوں صورتوں میں اسنیپ شاٹ پھر بھی مکمل ہوتا ہے اور مینی فیسٹ بتا دیتا ہے کہ کیا غائب ہے۔

مکملیت

server.listBackups فی اسنیپ شاٹ ایک complete فلیگ بتاتا ہے۔ یہ false ہوتا ہے جب مینی فیسٹ موجود نہ ہو یا پارس نہ ہو سکے، جب global.db غائب ہو، یا جب مینی فیسٹ کسی ایسی ورک اسپیس فائل کا نام لے جو ڈسک پر نہ ہو۔

نامکمل اسنیپ شاٹ پھر بھی فہرست میں شامل رہتا ہے، کیونکہ جو اسنیپ شاٹ کسی آپریٹر کو نظر نہ آئے، وہ اُس کے خیال میں اُس کے پاس موجود ہوتا ہے۔ جب مینی فیسٹ ناقابلِ مطالعہ ہو تو فہرست خود ساخت پر واپس گر جاتی ہے اور جو بھی <workspaceId>/workspace.db فائلیں اُسے ملتی ہیں اُنہیں بتا دیتی ہے — ایسی فائلیں workspace.import کے ذریعے انفرادی طور پر اپنائی جا سکتی رہتی ہیں، چاہے پورا اسنیپ شاٹ کسی انسٹال کو بحال نہ کر سکے۔

بیک اپ میں کیا کچھ نہیں ہوتا

دونوں آرٹی فیکٹس صرف ڈیٹا بیسز ہیں۔ ورک اسپیس کی ڈائریکٹری اپنی ڈیٹا بیس سے زیادہ کچھ رکھتی ہے، اور باقی میں سے کچھ بھی ساتھ نہیں جاتا:

پاتھ	اسنیپ شاٹ میں؟	ورک اسپیس ایکسپورٹ میں؟
global.db	ہاں	نہیں
<workspaceId>/workspace.db	ہاں	ہاں (یہ خود وہ فائل ہے)
<workspaceId>/blobs/	نہیں	نہیں
<workspaceId>/skills/	نہیں	نہیں
<workspaceId>/agents/	نہیں	نہیں
<workspaceId>/chat_credentials/	نہیں	نہیں
<workspaceId>/spaces/<spaceId>/	نہیں	نہیں
<workspaceId>/pr_clones/	نہیں	نہیں
secrets.json	نہیں	نہیں
models/	نہیں	نہیں
meetings/<meetingId>/	نہیں	نہیں
rigs/	نہیں	نہیں

اِس میں سے کچھ قابلِ ضیاع ہے — spaces/ میں copy-on-write worktrees رکھے ہوتے ہیں جو ریپوز سے دوبارہ تیار کیے جاتے ہیں، pr_clones/ ایک کیش ہے، models/ دوبارہ ڈاؤن لوڈ ہو جاتا ہے، rigs/ مشین کی حالت ہے۔ کچھ ایسا نہیں ہے: blobs/ میں وہ پیسٹ کی گئی تصاویر رکھی ہوتی ہیں جن کی طرف ڈیٹا بیس کی قطاریں اشارہ کرتی ہیں، skills/ اور agents/ میں وہ فائلیں رکھی ہوتی ہیں جن کے ساتھ کوئی ایجنٹ چلتا ہے، اور secrets.json میں انسٹال کی ہر پیئرنگ کلید، فراہم کنندہ کی اسناد اور SSO ترتیب رکھی ہوتی ہے۔ باقی سب ڈھانپنے کے لیے بیک اپ اور بحالی دیکھیں۔

چیٹ ٹوکن دانستہ طور پر پیچھے رہ جاتے ہیں

chat_credentials/ کا ڈیٹا بیس کے اندر کے بجائے اُس کے پہلو میں رہنا ہی وجہ ہے کہ کسی اور کو دی گئی ورک اسپیس اپنے ساتھ کوئی زندہ بوٹ ٹوکن نہیں لے جاتی۔ چیٹ برج حوالہ دیکھیں۔

آپریشنز

انسٹال بیک اپ کے RPCs اور ورک اسپیس ایکسپورٹ/امپورٹ صرف fullClient کے لیے ہیں: کوئی پیئر شدہ فون اُنہیں شروع نہیں کر سکتا۔ ایسے سرور پر، جہاں کوئی بیک اپ پورٹ وائر ہی نہ ہو — مثلاً ڈیمو سرور — یہ سب مکمل طور پر غائب ہوتے ہیں، مسترد نہیں بلکہ ساختی طور پر غائب۔

آپریشن	قسم	دائرہ	کم سے کم کردار	آرگیومنٹس	واپسی
server.backupNow	mutate	انسٹال	انسٹال کا مالک	کوئی نہیں	{ok, path}
server.listBackups	read	انسٹال	انسٹال کا مالک	کوئی نہیں	{backups: [...]}
server.deleteBackup	mutate	انسٹال	انسٹال کا مالک	name	{ok}
workspace.export	read	ورک اسپیس	admin	کوئی نہیں	{ok, path}
workspace.import	mutate	ورک اسپیس	owner	source_path	{ok, workspace_id}
workspace.delete	mutate	انسٹال*	owner	id	رجسٹری قطار حذف شدہ نشان زد

• workspace.delete کا کوئی ورک اسپیس دائرہ نہیں، کیونکہ جس قطار کو یہ نشان زد کرتا ہے وہ عالمی رجسٹری میں رہتی ہے؛ اُس کا ہینڈلر کال کرنے والے کی بتائی گئی ورک اسپیس میں رکنیت جانچتا ہے اور owner کا تقاضا کرتا ہے۔

ہر جواب میں path سرور ہوسٹ پر ایک پاتھ ہوتا ہے۔

پورے انسٹال کا اسنیپ شاٹ دونوں لینوں پر مالک سے مشروط ہے

server.backupNow، server.listBackups اور server.deleteBackup کو انسٹال کا مالک درکار ہوتا ہے (ServerAuthority.serverOwner)، یعنی وہی گیٹ جو GET /backup/snapshot پر لگتا ہے۔ ایک اسنیپ شاٹ ہر ورک اسپیس کی ڈیٹا بیس گرفت میں لیتا ہے، چنانچہ صرف ایک ورک اسپیس کا ایڈمن ہونا باقیوں کے نظم کے لیے کافی نہیں ہوتا۔ حذف صرف فہرست میں شامل ٹائم اسٹیمپ ڈائریکٹری کا نام قبول کرتا ہے، کوئی من مانا سرور پاتھ نہیں، اور پورا اسنیپ شاٹ ہٹاتا ہے (نامکمل اسنیپ شاٹس سمیت)۔ فی ورک اسپیس ایکسپورٹ/امپورٹ ورک اسپیس کے ایڈمن/مالک پر ہی رہتے ہیں، انسٹال کے مالک پر نہیں۔

server.listBackups کا جواب

نئے سے پرانے کی ترتیب میں، ڈائریکٹری کے نام سے ترتیب دیے گئے (جو ٹائم اسٹیمپ ہے، چنانچہ ترتیب اُس اسنیپ شاٹ کے لیے بھی برقرار رہتی ہے جس کا مینی فیسٹ پڑھا نہ جا سکا ہو)۔

{
  "backups": [
    {
      "path": "/…/backups/2026-07-28T09-12-33-000Z",
      "name": "2026-07-28T09-12-33-000Z",
      "created_at": "2026-07-28T09:12:33.000Z",
      "bytes": 481203712,
      "complete": true,
      "workspaces": [
        {
          "workspace_id": "w_9f2c…",
          "path": "/…/backups/2026-07-28T09-12-33-000Z/w_9f2c…/workspace.db",
          "bytes": 190840832
        }
      ],
      "skipped_workspace_ids": []
    }
  ]
}

created_at اُس وقت حذف ہو جاتا ہے جب مینی فیسٹ پڑھا نہ جا سکا ہو۔ اوپر کی سطح پر bytes پوری ڈائریکٹری کا ڈسک پر اصل سائز ہے، نہ کہ مینی فیسٹ کا اپنا مجموعہ — جو آپریٹر اسنیپ شاٹس چھانٹتے ہوئے پوچھ رہا ہوتا ہے، وہ یہ ہے کہ ڈائریکٹری کتنی جگہ لیتی ہے، نہ یہ کہ بیک اپ نے کتنا لکھنا چاہا تھا۔

ہر workspaces[].path بالکل وہی چیز ہے جو workspace.import source_path کے طور پر لیتا ہے۔ یہ جان بوجھ کر ایسا ہے: ”اِس ورک اسپیس کو اِس اسنیپ شاٹ سے بحال کریں“ وہی امپورٹ آپریشن ہے، چنانچہ یہ دونوں ایک ہی فائل کے ساتھ مختلف سلوک کی طرف سرک نہیں سکتے۔

workspace.import کی توثیق

کچھ بھی تبدیل ہونے سے پہلے، امیدوار فائل کو ایک قلیل المدت خام SQLite کنکشن کے ساتھ صرف پڑھنے کے لیے کھولا جاتا ہے اور اُس کی workspace_meta قطار پڑھی جاتی ہے۔

شرط	نتیجہ
کوئی خواندہ SQLite ڈیٹا بیس نہ ہو، یا workspace_meta نہ ہو	مسترد۔ کچھ بھی نہیں چھیڑا جاتا
ریکارڈ شدہ ورک اسپیس id ≠ ہدف	اجازت، لاگ ہوتا ہے۔ اِسی طرح کوئی ورک اسپیس نئی id کے تحت نقل یا بحال کی جاتی ہے
ریکارڈ شدہ انسٹال id ≠ یہ انسٹال	اجازت، لاگ ہوتا ہے۔ اُس کے پیئر شدہ ڈیوائسز اور صارف ids اُس انسٹال سے تعلق رکھتے ہیں اور یہاں حل نہیں ہوں گے
غلط ورک اسپیس id، یا فائل موجود نہ ہو	مسترد

قبول ہونے پر ہدف ورک اسپیس کی ڈیٹا بیس بند کر کے مینیجر سے ہٹا دی جاتی ہے، پھر اُس کے اوپر فائل کاپی کی جاتی ہے (ایک کھلا drift کنکشن فائل اور اُس کی -wal کو تھامے رکھتا ہے)، اور پھر دوبارہ کھولی جاتی ہے تاکہ beforeOpen FTS اور سنک ٹرگرز دوبارہ نصب کرے، اور FTS انڈیکسز دوبارہ بنائے جاتے ہیں — کسی امپورٹ شدہ فائل کے مواد کے ٹیبل بھرے ہوئے ہوتے ہیں مگر اُس کا انڈیکس باسی ہو سکتا ہے۔

منتقلی کے راستے

اوپر کا ہر آپریشن سرور کی طرف کے پاتھوں میں بات کرتا ہے، جو صرف اُس وقت مکمل جواب ہے جب سرور آپ کی اپنی مشین ہو۔ یہ تینوں بائٹس منتقل کرتے ہیں، اُسی PSK سے دستخط شدہ لین پر جسے میڈیا پراکسی اور بلاب اسٹور استعمال کرتے ہیں۔ کال کرنے والا اپنی ڈیوائس کی پری شیئرڈ کلید سے ایک ہدف سٹرنگ پر دستخط کرتا ہے اور دستخط کو s کے طور پر بھیجتا ہے۔

راستہ	میتھڈ	کوئری	دستخط شدہ ہدف	درکار
/backup/workspace	GET	w, d, s	backup-workspace:<workspaceId>	ورک اسپیس کا ایڈمن
/backup/snapshot	GET	n, d, s	backup-snapshot:<name>	انسٹال کا مالک
/backup/restore	POST	w, d, s	backup-restore:<workspaceId>	ورک اسپیس کا مالک

w ایک ورک اسپیس id ہے، n اسنیپ شاٹ ڈائریکٹری کا نام، d کال کرنے والے ڈیوائس کی id، اور s دستخط۔ n بیک اپ فہرست کے خلاف حل کیا جاتا ہے، بیک اپس روٹ پر جوڑ کر نہیں، چنانچہ راستے کو کسی ایسی ڈائریکٹری کی طرف نہیں موڑا جا سکتا جو فہرست ظاہر ہی نہ کرتی ہو۔

اسٹیٹس	وجہ
400	کوئی لازمی کوئری پیرامیٹر غائب ہو، یا اپ لوڈ باڈی خالی ہو
403	نامعلوم یا منسوخ شدہ ڈیوائس، خراب دستخط، یا کال کرنے والے کے پاس مطلوبہ کردار نہ ہو
404	اِس ہوسٹ پر کوئی بیک اپ پورٹ نہ ہو، یا بتائی گئی اسنیپ شاٹ/ورک اسپیس فائل موجود نہ ہو
405	/backup/restore کو POST کے سوا کسی اور چیز کے ساتھ کال کیا گیا ہو
413	اپ لوڈ باڈی 8 GiB سے بڑھ جائے، خواہ اعلان شدہ content-length سے یا واقعی پڑھے گئے بائٹس سے
500	ایکسپورٹ یا آرکائیو سرور کی طرف ناکام ہو گیا ہو

دونوں ڈاؤن لوڈز Cache-Control: no-store کے ساتھ Accept-Ranges: none کا جواب دیتے ہیں۔ ہر درخواست ایک تازہ نقل بناتی ہے اور اسٹریم ہونے کے بعد اُسے حذف کر دیتی ہے، چنانچہ کیش شدہ یا دوبارہ شروع کیا گیا جواب دو مختلف ایکسپورٹس کے بائٹس کو ایک ایسی فائل میں جوڑ دے گا جو دیکھنے میں درست لگتی ہے مگر ہے نہیں۔

/backup/snapshot، <name>.zip واپس کرتا ہے، جس کے اندراجات اسنیپ شاٹ روٹ کے حوالے سے ہوتے ہیں، چنانچہ اَن پیک کرنے پر manifest.json + global.db + <workspaceId>/workspace.db دوبارہ بن جاتے ہیں۔ اندراجات ترتیب شدہ صورت میں لکھے جاتے ہیں، لہٰذا ایک ہی اسنیپ شاٹ کے دو آرکائیو ایک ہی آرکائیو ہوتے ہیں۔

/backup/restore باڈی کو بفر کرنے کے بجائے براہِ راست ایک اسٹیجنگ فائل میں اسٹریم کرتا ہے، اُسے پڑھنے سے پہلے اور دورانِ مطالعہ محدود کرتا ہے، اور اسٹیج شدہ فائل کو باہر نکلنے کے ہر راستے پر حذف کر دیتا ہے، مسترد ہونے کی صورت سمیت۔

ریلے شدہ کنکشن کا کوئی HTTP اوریجن نہیں ہوتا

بروکرڈ ریلے RPC فریمز لے جاتا ہے، فائل ٹرانسفرز نہیں۔ جو کچھ سرور کی طرف کے پاتھوں میں بات کرتا ہے، وہ اُس پر چلتا رہتا ہے؛ تینوں منتقلی راستوں کو براہِ راست کنکشن درکار ہوتا ہے، اور UI اُنہیں ڈاؤن لوڈ کے بیچ میں ناکام کرنے کے بجائے ایک نوٹ کے ساتھ غیر فعال کر دیتا ہے۔

پاتھ اور حدیں

چیز	قدر
اسنیپ شاٹس	<dataDir>/backups/<timestamp>/
شیڈول شدہ ورک اسپیس بیک اپس	<dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db
ورک اسپیس ایکسپورٹس	<dataDir>/backups/exports/<workspaceId>-<timestamp>.db
منتقلی کی اسٹیجنگ	<dataDir>/backups/transfer/ — ایک ورک بینچ، جسے وہی راستہ صاف کرتا ہے جو اُسے لکھتا ہے
اسنیپ شاٹ آرکائیو کا نام	<snapshot directory name>.zip
اپ لوڈ کی حد	فی POST /backup/restore 8 GiB
برقراری	انسٹال اسنیپ شاٹس: دستی حذف۔ ورک اسپیس بیک اپس: ہفتہ وار پائپ لائن، بطور ڈیفالٹ 30 دن

exports/، transfer/ اور workspace-backups/ ڈائریکٹریاں انسٹال اسنیپ شاٹس نہیں ہیں اور server.listBackups سے خارج ہیں۔ صرف آخری ڈائریکٹری کی برقراری شیڈول شدہ ہے؛ کسی انسٹال اسنیپ شاٹ کو حذف کرنے کے لیے انسٹال کے مالک کی صریح کارروائی درکار ہوتی ہے۔

مزید دیکھیں

• بیک اپ اور بحالی — وہ ترکیبیں جن سے یہ آپریشنز تعلق رکھتے ہیں
• ورک اسپیسز اور تنہائی — ایک ورک اسپیس ایک فائل کیوں ہے
• cc_server CLI — وہ ڈیٹا ڈائریکٹری جس میں یہ پاتھ رہتے ہیں
• روٹ میپ — UI کہاں رہتا ہے
• آرکیٹیکچر — وہ کلائنٹ/سرور تقسیم جس کی پیروی یہ پاتھ کرتے ہیں