In this screencast Jeff Tang demonstrates how to load a personal Roam Research database into Athens, the open‑source Roam client, emphasizing privacy and data ownership. He walks through three straightforward steps: (1) run a DataScript query inside Roam to render the native database as an HTML table, (2) copy a prepared command into the browser console and then into a terminal to capture the table’s contents onto the clipboard, and (3) upload the resulting file to the static Athens site hosted on GitHub Pages. Throughout the demo he notes practical limits (databases larger than ~5‑6 GB may fail due to call‑stack limits), warns against exporting to Markdown/JSON because of data loss, and points out current shortcomings in Athens (missing title‑link parsing, formatting issues, red‑text parsing errors). He finishes by encouraging viewers to follow him on Twitter, star the GitHub repository, and experiment with the tool, while hinting at future enhancements such as handling multiple databases or merging them.
Chapters
Hi, Paul. Today I'm going to show you how to use your own Roam database with Athens, the open-source version of Roam. So a week and a half ago, I tweeted a little demo of me playing around with Athens, and I figured, you know, why not let people just use their own version of Athens? their Roam database. So this is for people that are worried about security and data privacy, people who are worried that, like, oh, Roam's a startup, what if they go out of business? Well, fear no more, because with this Athens client, then you'll always be able to explore your own Roam database with— while preserving bidirectional links. And yeah, so it's really simple. There's 3 easy steps. I definitely recommend you follow along. First, you need to open up Roam and copy this DataScript query. Go to any block, and after a few moments, a table should appear. Yeah, if your database is really big, this might not work. You know, I did this with the Roam Help database a few months ago, And there didn't seem to be a problem, but when I do it today, it doesn't seem to work. So I think after like 5 or 6 gigabytes, your Realm database might become too large for this to actually— this export to actually work. So maximum call stack size exceeded. Some other tips here are that you don't want to export as Markdown or JSON, you're losing data because you're not using the native database format that Roam uses. If you've ever tried to export Markdown and then import it back into Roam, some of the formatting— and it just doesn't work. So you also don't want to use window.alpha API. You can also make— there's another way to make a data script query, and room, but you lose some of your data there as well. So step 2 is you go to the command line and copy this. Now don't enter it in, like just copy it, but don't press enter yet because we need to add all of our data to our clipboard. So in your browser console, I'm using Chrome, copy this command and open your developer tools. You can press F12 as a shortcut and clear the console. Don't need that. Copy the command and you should get back undefined. That's fine. Basically, we parsed this HTML table and grabbed all the stuff within the cells and put it in our clipboard. Wrong terminal. It doesn't matter which terminal you use. The default one in Mac is Terminal. Press enter, and now you can see that there's stuff in there if you press head. And yeah, the final step is to actually upload this to Athens. Right now it's just a static site hosted on GitHub Pages, so there's no server. Yeah, you can go to GitHub, or you can just go to Yeah, this website directly. Again, it's just a static site. You can look at the source code and you'll see that nothing is being sent anywhere. None of your data, that is. Choose a file, and I'm going to upload the helpdb that I made. See, it's about 10 megabytes. My personal database. That's public is only 200 kilobytes, really small. Help database from a few months ago is 10 megabytes, so a lot bigger. And if you upload that, it takes, yeah, takes some time. And yeah, as you guys know, it takes some time to open Roam. But basically we're uploading 10 megabytes to this static site, and after a few moments it should populate with all the pages. Yeah, so just again, it's 3 simple steps. Don't have to do any coding, just copy and paste. Copy this to Chrome. Paste this. Copy this command to your terminal, but don't press Enter. Copy this in your browser console, and then press Enter. And finally, you upload the database. Oh yeah, there we go. So full screen. You might get something pop up on the right-hand side. You can press Ctrl+H. It's just a debugging tool. You can look at it too if you want to see how this works. So this is exactly like the Realm database, all the pages. I mean, this is exact in terms of the data. It's obviously not there yet. But yeah, if we go to new features, we can see all the linked references. Some of the links work. The ones in the title don't work yet. Need to fix that. But yeah, we can click around. And oh yeah. This is exactly, this is exactly the Realm database. You can tell because if we go to, if we copy this block ID and just paste it here, this will show us the actual new features in Realm. Look around, and yeah. So that's basically it. A lot of stuff doesn't work yet. Some links don't work. None of the formatting works. Like all the red text means it wasn't parsed correctly. But this uses the same language and database that Rome uses, which is Clojure and DataScript. So I don't think— it's very possible that I'll be able to implement all the same features. And yeah, if you want to see me keep on working on this, and yeah, if you like this, then make sure You follow me on Twitter, TangJaf0, and follow— sorry, and favorite this repository, star it on GitHub. Yeah, and just try it out. It's pretty cool, I think. Yeah, nothing happens if you upload your file multiple times. Probably make it so that You can use different databases or maybe even merge them, but yeah, nothing happens. So yeah, thanks for watching.
