Installing TimescaleDB on macOS with Postgres.app

2025-09-15T00:00:00+00:00

Why the "Easy Way" Didn't Work</a> </h2>

Postgres.app</a>. It's just the easiest way to manage PostgreSQL on a Mac. But recently, I ran into a bit of a headache when I tried to add TimescaleDB to the mix.

I started by following the official docs and tried the Homebrew method. "Easy peasy," I thought. But nope. It turns out that Homebrew's version of TimescaleDB is built for Homebrew's PostgreSQL, not the one from Postgres.app. This led to all sorts of annoying issues:

Target Mismatch: The extension was compiled for the wrong Postgres version.</li>
Missing Files: The .so</code> library files weren't where Postgres.app looked for them.</li>

Path Nightmares: I had multiple Postgres installations fighting each other.</li> </ol> After banging my head against the wall for a bit (and seeing a lot of empty directories where files should have been), I realized that compiling from source was actually the way to go.Why Building from Source is Better Here</a> </h2> When we build it ourselves, we can tell the build process exactly where our Postgres.app lives. This means: It uses the correct pg_config</code> from Postgres.app.</li> It puts the library files right where they need to be.</li> Everything is compatible with the specific version of Postgres you are running.</li> </ul> So, let's get to it! Here is the step-by-step guide I wish I had when I started. Step-by-Step Installation</a> </h2> Prerequisites</a> </h3> First off, make sure your Postgres.app is actually running. We also need to make sure your terminal knows where to find the Postgres tools. Run this to check: which pg_config # You want to see something like: /Applications/Postgres.app/Contents/Versions/latest/bin/pg_config</code></pre> If it shows a different path (like /usr/local/bin/...</code>), you need to update your path. Add this to your ~/.zshrc</code> or ~/.bash_profile</code>: export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"</code></pre> Don't forget to restart your terminal or run source ~/.zshrc</code> after saving! Step 1: Clean Slate (Optional)</a> </h3> If you already tried the Homebrew method and it failed, let's clean that up first so we don't have conflicts. brew uninstall timescaledb brew untap timescale/tap</code></pre>Step 2: Get the Build Tools</a> </h3> We need cmake</code> to build the project. If you don't have it yet: brew install cmake</code></pre>Step 3: Download TimescaleDB</a> </h3> Let's grab the code from GitHub. # Clone the repo git clone https://github.com/timescale/timescaledb.git cd timescaledb # I'm using version 2.21.1 here, but feel free to check out the latest stable tag git checkout 2.21.1</code></pre>Step 4: Configure the Build</a> </h3> This is the important part. We need to configure the build so it knows about our Postgres.app environment. OPENSSL_ROOT_DIR=/opt/homebrew/opt/openssl ./bootstrap -DREGRESS_CHECKS=OFF</code></pre> Note for Intel Mac users: If the path above doesn't work, your OpenSSL might be in a different spot. Try this instead: OPENSSL_ROOT_DIR=/usr/local/opt/openssl ./bootstrap -DREGRESS_CHECKS=OFF</code></pre> Quick tip: We use -DREGRESS_CHECKS=OFF</code> because the regression tests need some extra binaries that we don't strictly need just to get the extension running. Step 5: Compile and Install</a> </h3> Time to build! This might take a few minutes, so maybe grab a coffee ☕. cd ./build && make sudo make install</code></pre> When you run sudo make install</code>, it will copy the compiled files into your Postgres.app application bundle. This is exactly what we want! Step 6: Tell Postgres About It</a> </h3> Now we need to enable the library in your Postgres config. Find your config file: psql -d postgres -c "SHOW config_file;"</code></pre> Open that file in VS Code (or Vim if you're feeling brave) and look for shared_preload_libraries</code>. Change it to: shared_preload_libraries = 'timescaledb'</code></pre>Step 7: Restart and Enable</a> </h3> Important: Quit Postgres.app completely (Command+Q) and open it again. Just restarting the server isn't enough to load the new library.</li> Connect to your database and create the extension:</li> </ol> CREATE EXTENSION IF NOT EXISTS timescaledb;</code></pre> If you see the welcome message, congratulations! You did it! 🎉 Step 8: Let's Test It</a> </h3> Just to be 100% sure, let's make a quick hypertable. -- 1. Create a regular table CREATE TABLE conditions ( time TIMESTAMPTZ NOT NULL, location TEXT NOT NULL, temperature DOUBLE PRECISION NULL ); -- 2. Turn it into a hypertable SELECT create_hypertable('conditions', 'time'); -- 3. Add some data INSERT INTO conditions VALUES (NOW(), 'Bangkok', 32.5), (NOW() - INTERVAL '1 hour', 'Chiang Mai', 28.2); -- 4. Check if it's there SELECT * FROM conditions ORDER BY time DESC;</code></pre> Hope this guide saved you some time! Happy coding! 🚀

Step 8: Let's Test It

My Blog

Installing TimescaleDB on macOS with Postgres.app

Step 7: Restart and Enable </a> </h3>
Step 8: Let's Test It

Welcome to My Blog

My Blog

Installing TimescaleDB on macOS with Postgres.app

Step 7: Restart and Enable</a> </h3> Important:</strong> Quit Postgres.app completely (Command+Q) and open it again. Just restarting the server isn't enough to load the new library.</li>

Welcome to My Blog

Step 7: Restart and Enable </a> </h3>
Step 8: Let's Test It